ModeShape can be installed into an existing JBoss EAP 6.1. If you already have one, then you also have the $JBOSS_HOME environment variable set to the installation location.
As of ModeShape 3.2, ModeShape supports JBoss EAP 6.1, whereas earlier version of ModeShape supported AS7.1.1. See why. Installation is basically the same for both:
If you don't already have an EAP installation, download the JBoss EAP 6.1.x archive and unzip it into a known location (e.g., /apps/jboss-eap-6.1.1). Please refer to the EAP documentation Guide for requirements and installation instructions, and be sure the "$JBOSS_HOME" environment variable is set correctly to the path where EAP is installed.
If you need to run ModeShape 3.0.x or 3.1, then you will need to download JBoss AS7.1.1. Simply download the archive and unzip it into a known location (e.g., /apps/jboss-7.1.1). Please refer to the JBoss AS 7 Getting Started Guide for requirements and installation instructions, and be sure the "$JBOSS_HOME" environment variable is set correctly to the path where AS7 is installed.
The rest of this documentation will refer to EAP, but AS7.1.1 will apply as well, though anything specific to AS7.1.1 will be highlighted.
Download the latest ModeShape EAP kit (latest version is 3.8.1.Final). This kit is a ZIP archive that is intended to be unzipped directly into the EAP installation. Doing so will not override any of the files in the standard EAP installation.
The directory structure of the ModeShape EAP kit is as follows:
/docs
/schema
modeshape_1_0.xsd
/domain
/configuration
domain-modeshape.xml
modeshape-users.properties
modeshape-roles.properties
/modules
/javax/jcr/*
/org/modeshape/*
/org/hibernate/*
/org/infinispan
/org/apache/*
/standalone
/configuration/
standalone-modeshape.xml
standalone-modeshape-ha.xml
modeshape-users.properties
modeshape-roles.properties
AS you can see, the kit contains installs the "modeshape_1_0.xsd" into the existing /docs/schema directory, which is where all of the XML schemas for the application server subsystems are defined. The modeshape_1_0.xsd schema defines the entire structure of the ModeShape subsystem fragment in the server's XML configurations.
The kit installs modules for the JCR API (e.g., the javax.jcr packages), for ModeShape and its components, for the Hibernate Search engine, and for Apache Lucene. The latter two modules do not exist in the standard EAP/AS7 installation, but ModeShape explicitly avoided using the "main" slot on these modules in the off chance that you might have already defined such modules in your installation.
The standalone/configuration or domain/configuration folders contain two files that define the users and roles for the default security domain used by ModeShape:
modeshape-users.properties
modeshape-roles.properties
You can edit these files to add users, or define your different security domain by defining for each user the ModeShape roles found in the modeshape-roles.properties file.
The kit also installs several out-of-the-box configuration files:
standalone/configuration/standalone-modeshape.xml - contains 2 predefined repositories "sample" & "artifacts" and should be used when running a single EAP/AS7 instance.
standalone/configuration/standalone-modeshape-ha.xml - contains the same "sample" & "artifacts" repositories but configured in clustered mode. This configuration should be used when using multiple AS7/EAP nodes in replicated clustered mode.
domain/configuration/domain-modeshape.xml - contains the same configurations as in the standalone files, split up in several profiles: ha & full-ha contain the clustered repositories while full & default contain the standalone repositories.
Finally, the kit also deploys the "modeshape-rest", "modeshape-webdav" and "modeshape-cmis" web applications via the above configuration files. The web applications allow users to interact with ModeShape via the REST WebDAV and CMIS APIs respectively. If you don't want any of these applications to be deployed when the server starts up, comment out or remove the following configuration fragments:
<subsystem xmlns="urn:jboss:domain:modeshape:1.0"> <!--The list of web applications that is packaged inside the kit and should be deployed when the subsystem starts up--> <webapp name="modeshape-rest.war"/> <webapp name="modeshape-webdav.war"/> <webapp name="modeshape-cmis.war"/>
In addition to the default repository roles: admin, readwrite and read the role connect is required if a user wants to access any of the above described web applications that are deployed in AS7/EAP. Also, beware of spaces: do not use spaces before/after the commas as that will create incorrect role names.
At this point, you've installed ModeShape into your EAP installation, and it's ready to be used. Let's run the server in standalone mode with the provided "standalone-modeshape.xml" configuration:
$ bin/standalone.sh -c standalone-modeshape.xml
The server process will output a few dozen lines of messages, including one that says something similar to:
... 13:56:42,126 INFO [org.jboss.as] (MSC service thread 1-16) JBAS015874: JBoss EAP 6.1.1.Final started in 1957ms - Started 184 of 268 services (83 services are passive or on-demand)
At this point, the server is running and ready to accept requests at http://localhost:8080. If you want to see the "sample" repository in action, use your browser to go to http://localhost:8080/modeshape-rest or http://localhost:8080/modeshape-webdav to see http://localhost:8080/modeshape-rest/the information about the running repositories.
The resulting page is a JSON file that is difficult to read without formatting it in an editor. At this point, the content of the response is not important, but it simply shows that ModeShape is running with a "sample" repository.
To stop the server, simply hit CTRL-C in the terminal where AS7/EAP is running, and it will shutdown immediately but gracefully.
If you want the check out how a ModeShape repository can be clustered, you can start a couple of AS7/EAP nodes locally using the "standalone-modeshape-ha.xml" configuration file:
$ bin/standalone.sh -c standalone-modeshape-ha.xml -Djboss.node.name=node1
$ bin/standalone.sh -c standalone-modeshape-ha.xml -Djboss.node.name=node2 -Djboss.socket.binding.port-offset=100
As you can see, if you want to run several clustered nodes locally, there are 2 important properties you need to provide:
jboss.node.name - a symbolic name of the running AS7/EAP instance. This is required by JGroups to properly form the cluster members and will also be used by ModeShape when storing repository-related data
jboss.socket.binding.port-offset - a numeric value which will be used as an offset value for the various socket ports each instance opens. For example, by default the HTTP socket listens on port 8080. When passing the value 100, that AS7/EAP node will listen for HTTP connections on port 8180.
You can also run several ModeShape nodes (clustered or non-clustered) on different machines using the domain mode feature of AS7/EAP. Via the "domain-modeshape.xml" sample configuration file, you can start a domain controller with ModeShape pre-configured for each of the default domain profiles: ha, full-ha, full & default.
For more information about AS7/EAP domain mode, see: https://docs.jboss.org/author/display/AS71/AS7+Cluster+Howto and http://blog.akquinet.de/2012/06/29/managing-cluster-nodes-in-domain-mode-of-jboss-as-7-eap-6
Feel free to play with the sample repository through the REST API. However, since this is really just a sample configuration, we'll next see how to add ModeShape to other EAP configurations.